Skip to content

API Documentation

The AccountHub API is extremely simple to use. Requests can be sent via GET or POST, and responses are sent in JSON.

Request Structure

API URLs are typically of the form http(s)://accounthub-url/api/<action>/<api key>/?args.

The api key must match a key in the database table apikeys. The action specifies the type of request. Other arguments may or may not be needed, depending on the action specified. See the table below for valid actions and parameters.

Response Structure

Responses to well-formed requests will have a status field containing the string OK or ERROR.
If status is ERROR, there will also be a field named msg containing a human-readable localized error message suitable for display to the user.
If status is OK, there may or may not be additional fields sent, depending on the action.

If the request is not well-formed (missing required arguments, invalid credentials, or invalid action), the API will send a 4xx HTTP code and some plain text, such as "400 Bad Request", "403 Unauthorized", or "404 Action not defined".

Actions

Action Additional Arguments Description
ping None Used to check if the server is online and responding. Responds with {"status":"OK"}.
auth username, password Returns a status of OK if the user/pass combination are valid and allowed to login, otherwise returns ERROR. Also includes a msg with an error or success message.
userinfo username or uid If the username or UID exist in the system, returns the user's profile data in the data field.
Response format:
"data":{
"uid": "123",
"username": "jdoe",
"name": "John Doe",
"email": "[email protected]",
"phone": {
1: "1234567890",
2: ""
},
"pin": false/true
}
userexists username Returns a field exists which is true if the username exists or false if it does not.
Example response: {"status":"OK", "exists":true}
hastotp username Returns a field otp which is true if the user has 2-factor authentication setup or false if the user does not.
verifytotp username, code Checks if the given TOTP code is valid for the given user at the current time. Returns with {"status":"OK","valid":true} or {"status":"ERROR","msg":"<error message>","valid":false}.
acctstatus username Returns the account status in field account for the given username. Statuses are NORMAL, LOCKED_OR_DISABLED, CHANGE_PASSWORD (if password expired), TERMINATED, or ALERT_ON_ACCESS (like NORMAL except an alert email is sent to the system admin on successful login).
login username, password Simulates a system login, processing the account status, sending login alerts if needed, and noting a successful login in the security log. Returns a status of OK if it worked (with "alert": true if an admin alert was sent), or a status of ERROR if anything prevented a successful login.
ismanagerof manager, employee, uid (optional) Returns a boolean managerof which is true if manager is a manager of employee or false otherwise. If argument uid is present and equal to 1, manager and employee will be treated as UIDs, else as usernames.
getmanaged uid or username, get (optional) Returns an array of UIDs (or usernames if get=username) in employees corresponding to the users the given account is a manager of.
getmanagers uid or username Returns an array of UIDs in managers corresponding to the users the given account is managed by.
usersearch search Searches for users with names or usernames containing the search. Returns them in result as an array.
Response format:
"result":[
{
"uid":"123",
"username":"jdoe",
"name":"John Doe"
},
{
"uid":"124",
"username":"jadoe",
"name":"Jane Doe"
}
]
If search is less than three characters long, a search will not be attempted and result will be an empty array ([]). The result is also [] if no results are found.
permission uid or username, code Returns boolean has_permission if the given user has the given permission code. A list of valid permission codes are found in the database table permissions. Note: if a user has the ADMIN permission, this will always return true no matter what code is requested, because the user in question should have enough system access to give themselves the permission if so desired.
mobileenabled None Returns a boolean mobile to indicate the value of the config setting MOBILE_ENABLED.
mobilevalid username, code Returns a boolean valid to indicate if the supplied username and mobile code are valid.
alertemail username, appname (optional) Send alert email to system administrator regarding the specified user and application.
codelogin code Validate one-time code and (if successful) return username, realname, and uid for the user who generated the code. For code generation API, see /mobile/index.php
listapps None Get the list of configured apps from settings.php in {"apps":{}}.
getusersbygroup gid, get (optional) Get all the user IDs in the specified group. If get equals username, return usernames instead of user IDs. If get equals detail, return [{username: x, name: y, uid: z, pin: true}], where pin is true if the user has a PIN set, otherwise false.
getgroupsbyuser uid or username Get a list of groups as [{"id", "name"}] the given user (by ID or username) is a member of.
getgroups None Get a list of all user groups in the database.
groupsearch search Searches for groups with names containing the search. See usersearch for result format and more details. The differences are the fields returned (id and name) and the minimum query length (2 characters).
checkpin pin, username or uid Check if the supplied PIN matches the user's PIN. Returns a boolean pinvalid. If no PIN is set, returns a status ERROR, pinvalid false, and nopinset true.
getnotifications username or uid Get notifications for the user. When successful, returns an array notifications with items similar to: {"id": 1, "timestamp": "YYYY-MM-DD HH:MM:SS", "title": "text", "content": "text", "url": "text", "seen": false, "sensitive": false}
readnotification username or uid, id Mark the notification identified by the user and notification ID as read. Sets seen to true in future calls to getnotifications, and changes how the notification is displayed in the UI.
addnotification username or uid, title, content, timestamp (optional, defaults to current date/time), url (optional, defaults to empty string), sensitive (optional, defaults to false) Add a notification for the given user with the content.
deletenotification username or uid, id Delete the notification identified by the user and notifiation ID.